home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 4: GNU Archives / Linux Cubed Series 4 - GNU Archives.iso / gnu / sharutil.2 / sharutil / sharutils-4.2 / doc / sharutils.info < prev    next >
Encoding:
GNU Info File  |  1995-12-04  |  21.7 KB  |  579 lines
  1. This is Info file sharutils.info, produced by Makeinfo-1.63 from the
  2. input file sharutils.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Shar utilities: (sharutils).          GNU shar utilities.
  6. * mail-files: (sharutils)mail-files invocation. Send files to remote site.
  7. * mailshar: (sharutils)mailshar invocation.     Make and send a shell archive.
  8. * remsync: (sharutils)remsync invocation.       Synchronize remote files.
  9. * shar: (sharutils)shar invocation.             Make a shell archive.
  10. * unshar: (sharutils)unshar invocation.         Explode a shell archive.
  11. * uudecode: (sharutils)uudecode invocation.     Restore file from 7-bits.
  12. * uuencode: (sharutils)uuencode invocation.     Force binary file to 7-bits.
  13. END-INFO-DIR-ENTRY
  14.  
  15.    This file documents the GNU set of shar utilities.
  16.  
  17.    Copyright (C) 1994 Free Software Foundation, Inc.
  18.  
  19.    Permission is granted to make and distribute verbatim copies of this
  20. manual provided the copyright notice and this permission notice are
  21. preserved on all copies.
  22.  
  23.    Permission is granted to copy and distribute modified versions of
  24. this manual under the conditions for verbatim copying, provided that
  25. the entire resulting derived work is distributed under the terms of a
  26. permission notice identical to this one.
  27.  
  28.    Permission is granted to copy and distribute translations of this
  29. manual into another language, under the above conditions for modified
  30. versions, except that this permission notice may be stated in a
  31. translation approved by the Foundation.
  32.  
  33. 
  34. File: sharutils.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  35.  
  36. GNU `shar' utilities
  37. ********************
  38.  
  39.    GNU `shar' makes so-called shell archives out of many files,
  40. preparing them for transmission by electronic mail services.  GNU
  41. `unshar' helps unpacking shell archives after reception.  This is
  42. release 4.1.9.
  43.  
  44. * Menu:
  45.  
  46. * Introduction::                Introduction to both programs
  47. * shar invocation::             Invoking the `shar' program
  48. * unshar invocation::           Invoking the `unshar' program
  49. * Miscellaneous::               Miscellaneous considerations
  50.  
  51.  -- The Detailed Node Listing --
  52.  
  53. Creating shell archives
  54.  
  55. * Selecting::                   Selecting files
  56. * Splitting::                   Splitting output
  57. * Headers::                     Controlling the shar headers
  58. * Stocking::                    Selecting how files are stocked
  59. * Transmission::                Protecting against transmission
  60. * Kinds::                       Producing different kinds of shar
  61.  
  62. 
  63. File: sharutils.info,  Node: Introduction,  Next: shar invocation,  Prev: Top,  Up: Top
  64.  
  65. Introduction to both programs
  66. *****************************
  67.  
  68.    GNU `shar' makes so-called shell archives out of many files,
  69. preparing them for transmission by electronic mail services.  A "shell
  70. archive" is a collection of files that can be unpacked by `/bin/sh'.  A
  71. wide range of features provide extensive flexibility in manufacturing
  72. shars and in specifying shar *smartness*.  For example, `shar' may
  73. compress files, uuencode binary files, split long files and construct
  74. multi-part mailings, ensure correct unsharing order, and provide
  75. simplistic checksums.  *Note shar invocation::.
  76.  
  77.    GNU `unshar' scans a set of mail messages looking for the start of
  78. shell archives.  It will automatically strip off the mail headers and
  79. other introductory text.  The archive bodies are then unpacked by a
  80. copy of the shell.  `unshar' may also process files containing
  81. concatenated shell archives.  *Note unshar invocation::.
  82.  
  83.    GNU `shar' has a long history.  All along this long road, numerous
  84. users contributed various improvements.  The file `THANKS', from the
  85. GNU `shar' distribution, contain all names still having valid email
  86. addresses, as far as we know.
  87.  
  88.    Please help me getting the history straight, for the following
  89. information is approximative.  James Gosling wrote the public domain
  90. `shar 1.x'.  William Davidsen rewrote it as `shar 2.x'.  Warren Tucker
  91. brought modifications and called it `shar 3.x'.  Richard Gumpertz
  92. maintained it until 1990.  Franc,ois Pinard, from the public domain
  93. `shar 3.49', made `GNU shar 4.x', in 1994.  Some modules and other code
  94. sections were freely borrowed from other GNU distributions, bringing
  95. this `shar' under the terms of the GNU General Public License.
  96.  
  97.    Your feedback helps us to make a better and more portable product.
  98. Mail suggestions and bug reports (including documentation errors) for
  99. these programs to `bug-gnu-utils@prep.ai.mit.edu'.
  100.  
  101. 
  102. File: sharutils.info,  Node: shar invocation,  Next: unshar invocation,  Prev: Introduction,  Up: Top
  103.  
  104. Invoking the `shar' program
  105. ***************************
  106.  
  107.    The format of the `shar' command is one of:
  108.  
  109.      shar [ OPTION ] ... FILE ...
  110.      shar -S [ OPTION ] ...
  111.  
  112.    In the first form, the file list is given as command arguments.  In
  113. the second form, the file list is read from standard input.  The
  114. resulting archive is sent to standard output unless the `-o' option is
  115. given.
  116.  
  117.    Options can be given in any order.  Some options depend on each
  118. other: the `-o' option is required if the `-l' or `-L' option is used.
  119. The `-n' option is required if the `-a' option is used.  Also see `-V'
  120. below.
  121.  
  122.    Some options are special purpose:
  123.  
  124. `--help'
  125.      Print a help summary on standard output, then immediately exits.
  126.  
  127. `--version'
  128.      Print the version number of the program on standard output, then
  129.      immediately exits.
  130.  
  131. `-q'
  132. `--quiet'
  133.      Verbose *off* at `shar' time.  Messages are usually issued on
  134.      standard error to let the user follow the progress, while making
  135.      the archives.  This option inhibits these messages.
  136.  
  137. * Menu:
  138.  
  139. * Selecting::                   Selecting files
  140. * Splitting::                   Splitting output
  141. * Headers::                     Controlling the shar headers
  142. * Stocking::                    Selecting how files are stocked
  143. * Transmission::                Protecting against transmission
  144. * Kinds::                       Producing different kinds of shar
  145.  
  146. 
  147. File: sharutils.info,  Node: Selecting,  Next: Splitting,  Prev: shar invocation,  Up: shar invocation
  148.  
  149. Selecting files
  150. ===============
  151.  
  152. `-p'
  153. `--intermix-type'
  154.      Allow positional parameter options.  The options `-M', `-B', `-T',
  155.      `-z' and `-Z' may be embedded, and files to the right of the
  156.      option will be processed in the specified mode.  Without the `-p'
  157.      option, embedded options would be interpreted as file names.
  158.      *Note Stocking:: for more information on these options.
  159.  
  160. `-S'
  161. `--stdin-file-list'
  162.      Read list of files to be packed from the standard input rather
  163.      than from the command line.  Input must be one file name per line.
  164.      This switch is especially useful when the command line will not
  165.      hold the list of files to be packed.  For example:
  166.  
  167.           find . -type f -print | shar -S -o /tmp/big.shar
  168.  
  169.      If `-p' is specified on the command line, then the options `-M',
  170.      `-B', `-T', `-z' and `-Z' may be included in the standard input
  171.      (on a line separate from file names).  The maximum number of lines
  172.      of standard input, file names and options, may not exceed 1024.
  173.  
  174. 
  175. File: sharutils.info,  Node: Splitting,  Next: Headers,  Prev: Selecting,  Up: shar invocation
  176.  
  177. Splitting output
  178. ================
  179.  
  180. `-o PREFIX'
  181. `--output-prefix=PREFIX'
  182.      Save the archive to files `PREFIX.01' through `PREFIX.NNN' instead
  183.      of standard output.  This option *must* be used when the `-l' or
  184.      the `-L' switches are used.
  185.  
  186.      When PREFIX contains any `%' character, PREFIX is then interpreted
  187.      as a `sprintf' format, which should be able to display a single
  188.      decimal number.  When PREFIX does not contain such a `%'
  189.      character, the string `.%02d' is internally appended.
  190.  
  191. `-l SIZE'
  192. `--whole-size-limit=SIZE'
  193.      Limit the output file size to SIZE times 1024 bytes but don't
  194.      split input files.  This allows the recipient of the shell archives
  195.      to unpack them in any order.
  196.  
  197. `-L SIZE'
  198. `--split-size-limit=SIZE'
  199.      Limit output file size to SIZE times 1024 bytes and split files if
  200.      necessary.  The archives created with this option must be unpacked
  201.      in the correct order.  If the recipient of the shell archives
  202.      wants to put all of them in a single folder, she shall save them
  203.      in the correct order for `unshar', used with option `-e', to
  204.      unpack them all at once.  *Note unshar invocation::.
  205.  
  206.      For people used to saving all the shell archives into a single mail
  207.      folder, care must be taken to save them in the appropriate order.
  208.      For those having the appropriate tools (like Masanobu Umeda's
  209.      `rmailsort' package for GNU Emacs), shell archives can be saved in
  210.      any order, then sorted by increasing date (or send time) before
  211.      massive unpacking.
  212.  
  213. 
  214. File: sharutils.info,  Node: Headers,  Next: Stocking,  Prev: Splitting,  Up: shar invocation
  215.  
  216. Controlling the shar headers
  217. ============================
  218.  
  219. `-n NAME'
  220. `--archive-name=NAME'
  221.      Name of archive to be included in the header of the shar files.
  222.      Also see the `-a' switch further down.
  223.  
  224. `-s ADDRESS'
  225. `--submitter=ADDRESS'
  226.      The `-s' option allows for overriding the email address for the
  227.      submitter, for when the default is not appropriate.  The
  228.      automatically determined address looks like `USERNAME@HOSTNAME'.
  229.  
  230. `-a'
  231. `--net-headers'
  232.      Allows automatic generation of headers:
  233.  
  234.           Submitted-by: ADDRESS
  235.           Archive-name: NAME/partNN
  236.  
  237.      The NAME must be given with the `-n' switch.  If name includes a
  238.      `/', then `/part' isn't used. Thus `-n xyzzy' produces:
  239.           xyzzy/part01
  240.           xyzzy/part02
  241.  
  242.      while `-n xyzzy/patch' produces:
  243.           xyzzy/patch01
  244.           xyzzy/patch02
  245.  
  246.      and `-n xyzzy/patch01.' produces:
  247.           xyzzy/patch01.01
  248.           xyzzy/patch01.02
  249.  
  250. `-c'
  251. `--cut-mark'
  252.      Start the shar with a cut line.  A line saying `Cut here' is
  253.      placed at the start of each output file.
  254.  
  255. 
  256. File: sharutils.info,  Node: Stocking,  Next: Transmission,  Prev: Headers,  Up: shar invocation
  257.  
  258. Selecting how files are stocked
  259. ===============================
  260.  
  261. `-T'
  262. `--text-files'
  263.      Treat all files as text, regardless of their contents.
  264.  
  265. `-B'
  266. `--uuencode'
  267.      Treat all files as binary, use `uuencode' prior to packing. This
  268.      increases the size of the archive. The recipient must have
  269.      `uudecode' in order to unpack.
  270.  
  271.           Use of `uuencode' is not appreciated by many on the net, because
  272.           people like to readily see, by mere inspection of a shell archive,
  273.           what it is about.
  274.  
  275. `-M'
  276. `--mixed-uuencode'
  277.      Mixed mode.  Automatically determine if the files are text or
  278.      binary and archive correctly.  Files found to be binary are
  279.      uuencoded prior to packing.  This option is selected by default.
  280.  
  281.      For a file is considered to be a text file, instead of a binary
  282.      file, all the following should be true simultaneously:
  283.        1. The file does not contain any ASCII control character besides
  284.           BS (backspace), HT (horizontal tab), LF (new line) or FF
  285.           (form feed).
  286.  
  287.        2. The file does not contains a DEL (delete).
  288.  
  289.        3. The file contains no character with its eighth-bit set.
  290.  
  291.        4. The file, unless totally empty, terminates with a LF
  292.           (newline).
  293.  
  294.        5. No line in the file contains more than 200 characters.  For
  295.           counting purpose, lines are separated by a LF (newline).
  296.  
  297. `-z'
  298. `--gzip'
  299.      Use `gzip' and `uuencode' on all files prior to packing.  The
  300.      recipient must have `uudecode' and `gzip' (used with `-d') in
  301.      order to unpack.
  302.  
  303.      Usage of `-z' in net shars will cause you to be flamed off the
  304.      earth.
  305.  
  306. `-g LEVEL'
  307. `--level-for-gzip=LEVEL'
  308.      When doing compression, use `-LEVEL' as a parameter to `gzip'.
  309.      The `-g' option turns on the `-z' option by default.  The default
  310.      value is 9, that is, maximum compression.
  311.  
  312. `-Z'
  313. `--compress'
  314.      Use `compress' and `uuencode' on all files prior to packing.  The
  315.      recipient must have `uudecode' and `compress' (used with `-d') in
  316.      order to unpack.  Option `-C' is a synonymous for `-Z', but is
  317.      deprecated.
  318.  
  319.      Usage of `-Z' in net shars will cause you to be flamed off the
  320.      earth.
  321.  
  322. `-b BITS'
  323. `--bits-per-code=BITS'
  324.      When doing compression, use `-bX' as a parameter to `compress'.
  325.      The `-B' option turns on the `-Z' option by default.  The default
  326.      value is 12, foreseeing the memory limitations of some `compress'
  327.      programs on smallish systems, at `unshar' time.
  328.  
  329. 
  330. File: sharutils.info,  Node: Transmission,  Next: Kinds,  Prev: Stocking,  Up: shar invocation
  331.  
  332. Protecting against transmission errors
  333. ======================================
  334.  
  335.    Transmission of shell archives is not always free of errors.  So one
  336. should make consistency checks on the receiving site.  A very simple
  337. (and unreliable) method is running the UNIX `wc' tool on the output
  338. file.  This can report the number of characters in the file.
  339.  
  340.    As one can guess this does not catch all errors.  Especially
  341. changing of a character value does not change the computed check sum.
  342. To achieve this goal better method were invented and standardized.  One
  343. very strong is MD5 (MD = message digests).  This is standardized in RFC
  344. 1321.  The produced shell scripts do not force the `md5sum' program to
  345. be installed on the system.  This is necessary because it is not yet
  346. part of every UNIX.  The program is however not necessary for producing
  347. the shell archive.
  348.  
  349. `-w'
  350. `--no-character-count'
  351.      Do *not* check with `wc -c' after unpack.  The default is to check.
  352.  
  353. `-D'
  354. `--no-md5-digest'
  355.      Do *not* check with `md5sum' after unpack.  The default is to
  356.      check.
  357.  
  358. `-F'
  359. `--force-prefix'
  360.      Prepend the prefix character to every line even if not required.
  361.      This option may slightly increase the size of the archive,
  362.      especially if `-B' or `-Z' is used.  Normally, the prefix character
  363.      is `X'.  If the parameter to the `-d' option starts with `X', then
  364.      the prefix character becomes `Y'.
  365.  
  366. `-d STRING'
  367. `--here-delimiter=STRING'
  368.      Use STRING to delimit the files in the shar instead of `SHAR_EOF'.
  369.      This is for those who want to personalize their shar files.
  370.  
  371. 
  372. File: sharutils.info,  Node: Kinds,  Prev: Transmission,  Up: shar invocation
  373.  
  374. Producing different kinds of shars
  375. ==================================
  376.  
  377. `-V'
  378. `--vanilla-operation'
  379.      This option produces "vanilla" shars which rely only upon the
  380.      existence of `echo', `test' and `sed' in the unpacking environment.
  381.  
  382.      The `-V' disables options offensive to the "network cop" (or
  383.      "brown shirt").  It also changes the default from mixed mode `-M'
  384.      to text mode `-T'.  Warnings are produced if option `-B', `-z',
  385.      `-Z', `-p' or `-M' is specified (any of which does or might
  386.      require `uudecode', `gzip' or `compress' in the unpacking
  387.      environment).
  388.  
  389. `-P'
  390. `--no-piping'
  391.      In the shar file, use a temporary file to hold the file to
  392.      `uudecode', instead of using pipes.  This option is mandatory when
  393.      you know the unpacking `uudecode' is unwilling to merely read its
  394.      standard input.  Richard Marks wrote what is certainly the most
  395.      (in)famous of these, for MSDOS :-).
  396.  
  397.      (Here is a side note from the maintainer.  Why isnt't this option
  398.      the default?  In the past history of `shar', it was decided that
  399.      piping was better, surely because it is less demanding on disk
  400.      space, and people seem to be happy with this.  Besides, I think
  401.      that the `uudecode' from Richard Marks, on MSDOS, is wrong in
  402.      refusing to handle `stdin'.  So far that I remember, he has the
  403.      strong opinion that a program without any parameters should give
  404.      its `--help' output.  Besides that, should I say, his `uuencode'
  405.      and `uudecode' programs are full-featured, one of the most
  406.      complete set I ever saw.  But Richard will not release his
  407.      sources, he wants to stay in control.)
  408.  
  409. `-x'
  410. `--no-check-existing'
  411.      Overwrite existing files without checking.  If neither `-x' nor
  412.      `-X' is specified, when unpacking itself, the shell archive will
  413.      check for and not overwrite existing files (unless `-c' is passed
  414.      as a parameter to the script when unpacking).
  415.  
  416. `-X'
  417. `--query-user'
  418.      Interactively overwrite existing files.
  419.  
  420.      Use of `-X' produces shars which *will* cause problems with some
  421.      `unshar'-style procedures, particularily when used together with
  422.      vanilla mode (`-V').  Use this feature mainly for archives to be
  423.      passed among agreeable parties.  Certainly, `-X' is *not* for
  424.      shell archives which are to be submitted to Usenet or other public
  425.      networks.
  426.  
  427.      The problem is that `unshar' programs or procedures often feed
  428.      `/bin/sh' from its standard input, thus putting `/bin/sh' and the
  429.      shell archive script in competition for input lines.  As an
  430.      attempt to alleviate this problem, `shar' will try to detect if
  431.      `/dev/tty' exists at the receiving site and will use it to read
  432.      user replies.  But this does not work in all cases, it may happen
  433.      that the receiving user will have to avoid using `unshar' programs
  434.      or procedures, and call `/bin/sh' directly.  In vanilla mode,
  435.      using `/dev/tty' is not even attempted.
  436.  
  437. `-m'
  438. `--no-timestamp'
  439.      Avoid generating `touch' commands to restore the file modification
  440.      dates when unpacking files from the archive.
  441.  
  442.      When the timestamp relationship is not preserved, some files like
  443.      `configure' or `*.info' may be uselessly remade after unpacking.
  444.      This is why, when this option is not used, a special effort is
  445.      made to restore timestamps,
  446.  
  447. `-Q'
  448. `--quiet-unshar'
  449.      Verbose *off* at `unshar' time.  Disables the inclusion of
  450.      comments to be output when the archive is unpacked.
  451.  
  452. `-f'
  453. `--basename'
  454.      Use only the last file name component of each input file name,
  455.      ignoring any prefix directories.  This is sometimes useful when
  456.      building a shar from several directories, or another directory.
  457.      If a directory name is passed to `shar', the substructure of that
  458.      directory will be restored whether `-f' is specified or not.
  459.  
  460. 
  461. File: sharutils.info,  Node: unshar invocation,  Next: Miscellaneous,  Prev: shar invocation,  Up: Top
  462.  
  463. Invoking the `unshar' program
  464. *****************************
  465.  
  466.    The format of the `unshar' command is:
  467.  
  468.      unshar [ OPTION ] ... [ FILE ... ]
  469.  
  470.    Each FILE is processed in turn, as a shell archive or a collection
  471. of shell archives.  If no files are given, then standard input is
  472. processed instead.
  473.  
  474.    Options:
  475.  
  476. `--version'
  477.      Print the version number of the program on standard output, then
  478.      immediately exits.
  479.  
  480. `--help'
  481.      Print an help summary on standard output, then immediately exits.
  482.  
  483. `-d DIRECTORY'
  484. `--directory=DIRECTORY'
  485.      Change directory to DIRECTORY before unpacking any files.
  486.  
  487. `-c'
  488. `--overwrite'
  489. `-f'
  490. `--force'
  491.      Passed as an option to the shar file.  Many shell archive scripts
  492.      (including those produced by `shar' 3.40 and newer) accepts a `-c'
  493.      argument to indicate that existing files should be overwritten.
  494.  
  495.      The option `-f' is provided for a more unique interface.  Many
  496.      programs (such as `cp' and `mv') use this option to trigger the
  497.      very same action.
  498.  
  499. `-e'
  500. `--exit-0'
  501.      This option exists mainly for people who collect many shell
  502.      archives into a single mail folder.  With this option, `unshar'
  503.      isolates each different shell archive from the others which have
  504.      been put in the same file, unpacking each in turn, from the
  505.      beginning of the file towards its end.  Its proper operation
  506.      relies on the fact that many shar files are terminated by a
  507.      `exit 0' at the beginning of a line.
  508.  
  509.      Option `-e' is internally equivalent to `-E "exit 0"'.
  510.  
  511. `-E STRING'
  512. `--split-at=STRING'
  513.      This option works like `-e', but it allows you to specify the
  514.      string that separates archives if `exit 0' isn't appropriate.
  515.  
  516.      For example, noticing that most `.signatures' have a `--' on a
  517.      line right before them, one can sometimes use `--split-at=--' for
  518.      splitting shell archives which lack the `exit 0' line at end.  The
  519.      signature will then be skipped altogether with the headers of the
  520.      following message.
  521.  
  522. 
  523. File: sharutils.info,  Node: Miscellaneous,  Prev: unshar invocation,  Up: Top
  524.  
  525. Miscellaneous considerations
  526. ****************************
  527.  
  528.    Here is a place-holder for many considerations which do not fit
  529. elsewhere, while not worth a section for themselves.
  530.  
  531.    Be careful that the output file(s) are not included in the inputs or
  532. `shar' may loop until the disk fills up.  Be particularly careful when
  533. a directory is passed to `shar' that the output files are not in that
  534. directory (or a subdirectory of that directory).
  535.  
  536.    When a directory is passed to `shar', it may be scanned more than
  537. once, to conserve memory.  Therefore, one should be careful to not
  538. change the directory contents while `shar' is running.
  539.  
  540.    No attempt is made to restore the protection and modification dates
  541. for directories, even if this is done by default for files.  Thus, if a
  542. directory is given to `shar', the protection and modification dates of
  543. corresponding unpacked directory may not match those of the original.
  544.  
  545.    Use of the `-M' or `-B' options will slow down the archive process.
  546. Use of the `-z' or `-Z' options may slow the archive process
  547. considerably.
  548.  
  549.    Let us conclude by a showing a few examples of `shar' usage:
  550.  
  551.      shar *.c > cprog.shar
  552.      shar -Q *.[ch] > cprog.shar
  553.      shar -B -l28 -oarc.sh. *.arc
  554.      shar -f /lcl/src/u*.c > u.sh
  555.  
  556. The first shows how to make a shell archive out of all C program
  557. sources.  The second produces a shell archive with all `.c' and `.h'
  558. files, which unpacks silently.  The third gives a shell archive of all
  559. uuencoded `.arc' files, into files `arc.sh.01' through to `arc.sh.NNN'.
  560. The last example gives a shell archive which will use only the file
  561. names at unpack time.
  562.  
  563.  
  564. 
  565. Tag Table:
  566. Node: Top1489
  567. Node: Introduction2494
  568. Node: shar invocation4478
  569. Node: Selecting5980
  570. Node: Splitting7111
  571. Node: Headers8750
  572. Node: Stocking9915
  573. Node: Transmission12494
  574. Node: Kinds14174
  575. Node: unshar invocation18124
  576. Node: Miscellaneous20237
  577. 
  578. End Tag Table
  579.